============
Installation
============

REQUIREMENTS
============

* A Unix-like operating system (e.g., BSD, illumos, Linux, or macOS).

* Python_ v3.9 or later.

* The `Package Installer for Python`_ (:command:`pip`)


DOWNLOAD
========

Download the most recent release::

    curl -O https://codeberg.org/odkr/sievemgr/releases/download/v0.7.2/sievemgr-0.7.2.tgz

Optionally, check whether the tarball has been tampered with::

    curl -O https://codeberg.org/odkr/sievemgr/releases/download/v0.7.2/sievemgr-0.7.2.tgz.asc
    gpg --recv-key 8975B184615BC48CFA4549056B06A2E03BE31BE9
    gpg --verify sievemgr-0.7.2.tgz.asc

Unpack the tarball::

    tar -xzf sievemgr-0.7.2.tgz

Go to the top-level directory of the repository::

    cd sievemgr-0.7.2


INSTALLATION
============

Home directory
--------------

Install SieveManager to your home directory::

    make userinstall

The manual pages are copied to :file:`~/.local/share/man`.
Consult the manual of your system's :command:`man` or your shell
on how to add that directory to your :envvar:`MANPATH`.

The Bash completion script is copied to
:file:`~/.local/share/bash-completion/completions`,
the Zsh completion script to
:file:`~/.local/share/zsh-completions`.


Virtual environment
-------------------

Store the installation directory in :envvar:`venvdir`::

    venvdir=/opt/odkr/sievemgr

Create a virtual environment in :envvar:`venvdir`::

    python3 -mvenv "${venvdir:?}"

Install SieveManager to the virtual environment::

    make venvdir="${venvdir:?}" vinstall

Symlink :command:`sievemgr` into a directory in the system's :envvar:`PATH`::

    ln -s "${venvdir:?}/bin/sievemgr" /usr/local/bin

.. TIP::
    Install SieveManager to :envvar:`venvdir`, but copy the manual pages
    to :file:`/usr/local/share/man`, the Bash completion script to
    :file:`/usr/local/share/bash-completion/completions`, and the Zsh
    completion script to :file:`/usr/local/share/zsh-completions`::

        make venvdir="$venvdir" prefix=/usr/local vinstall


Manual
------

SieveManager can also be installed by being copied into a
directory in your :envvar:`PATH`::

    install sievemgr.py ~/.local/bin/sievemgr

----

That said, you should also install the cryptography_ Python module::

    python3 -mpip install cryptography

:mod:`cryptography` is needed to check whether a server's TLS
certificate has been revoked.

----

You may also want to install the dnspython_ Python module::

    python3 -mpip install dnspython

:mod:`dnspython` is needed to resolve DNS `SRV records`_.
Most ManageSieve servers do not have SRV records, however.


DE-INSTALLATION
===============

Uninstall SieveManger::

    make uninstall

.. NOTE::
    :mod:`cryptography` and :mod:`dnspython` are installed automatically by
    :command:`make userinstall` and :command:`make vinstall`. However,
    they are *not* uninstalled by :command:`make uninstall`.


EXTRAS
======

Bash completion
---------------

The Bash completion script should work automatically if the bash-completion_
package is installed.

However, it can also be loaded by adding, for example,

.. code:: bash

    source "$HOME/.local/share/bash-completion/completions/sievemgr.bash"

to your :file:`.bashrc`.


Zsh completion
--------------

The Zsh completion script targets Zsh's modern `completion system
<Zsh completion_>`_.

It can be activated by adding, for example,

.. code:: zsh

    fpath+=("$HOME/.local/share/zsh-completions")

    autoload -Uz compinit
    compinit

to your :file:`.zshrc`.


PACKAGING
=========

See :doc:`packaging` for an example how to package
SieveManager for Debian_.


.. _Debian: https://www.debian.org

.. _`Package Installer for Python`: https://pypi.org/project/pip/

.. _Python: https://www.python.org/

.. _`Zsh completion`: https://zsh.sourceforge.io/Doc/Release/Completion-System.html

.. _bash-completion: https://github.com/scop/bash-completion

.. _cryptography: https://cryptography.io

.. _dnspython: https://www.dnspython.org
